/*
 * Copyright (c) 2022 Queclink-C-Library
 *
 * This file is subject to the terms and conditions of the MIT License.
 * For details, please see the LICENSE file or visit the MIT website: https://mit-license.org/
 */

#ifndef QLIBC_MEMORY_H
#define QLIBC_MEMORY_H

#include <stddef.h>
#include <string.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup memory
 * @ingroup common
 * @brief Declare by `#include <qlibc/memory.h>`. Operations related to memory (not string).
 * @{
 */

/**
 * @brief   Find a string in memory area, ignoring the case of the characters.
 * @param[in] buf The memory area to be searched.
 * @param[in] n   The number of bytes to be searched.
 * @param[in] str The string to search for, ignoring the case of the characters.
 * @return  Return the pointer to the string in memory area, or \b NULL if string is not found.
 * @note    The terminator '\0' of string is ignored when searching.
 * @sa      quec_memstr
 * @authors Hubert.Lee, Schuyler.Zhang
 * @date    2022/7/7
 */
char *quec_memcasestr(const void *buf, size_t n, const char *str);

/**
 * @brief   Find the content specified by `sbuf` in the memory area specified by `buf`.
 * @param[in] buf  The memory area to be searched.
 * @param[in] n    The number of bytes to be searched.
 * @param[in] sbuf The content to search for.
 * @param[in] sn   The number of bytes of `sbuf`.
 * @return  Return the pointer to the content in memory area, or \b NULL if `sbuf` is not found.
 * @authors Hubert.Lee, Jason.Huang
 * @date    2022/7/7
 */
void *quec_memsrch(const void *buf, size_t n, const void *sbuf, size_t sn);

/**
 * @brief   Find a string in memory area.
 * @param[in] buf The memory area to be searched.
 * @param[in] n   The number of bytes to be searched.
 * @param[in] str The string to search for.
 * @return  Return the pointer to the string in memory area, or \b NULL if string is not found.
 * @note    The terminator '\0' of string is ignored when searching.
 * @sa      quec_memcasestr
 * @authors Hubert.Lee, Terry.Huang
 * @date    2022/5/30
 */
char *quec_memstr(const void *buf, size_t n, const char *str);

/**
 * @brief   Remove whitespace characters ( `isspace()` ) and control characters ( `iscntrl()` ) from the leading and trailing of a memory area.
 * @param[in,out] buf   The user provides a memory area, and we change it to a new one with the leading and trailing characters removed.
 * @param[in]     n     The initial number of bytes of the memory area.
 * @return  The number of bytes of the memory area with the leading and trailing characters removed.
 * @authors Hubert.Lee, Schuyler.Zhang
 * @date    2022/7/7
 */
size_t quec_memtrim(void *buf, size_t n);

/** memory
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* QLIBC_MEMORY_H */
